chore: add centralized docs - #2802
Open
Tofel wants to merge 2 commits into
Open
Conversation
Tofel
force-pushed
the
dx-5122-alerts-assertion-p15
branch
from
September 7, 2026 09:35
58d2316 to
9fa7199
Compare
Tofel
marked this pull request as ready for review
September 7, 2026 09:38
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The quickstart snippets reference shell variables that are never set (they “emit” timestamps but don’t capture them), making the primary usage examples non-runnable/ambiguous.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR centralizes and expands documentation for grafana-alertcheck, moving from a minimal README to a structured docs set (overview, concepts, reference, and architecture) intended for a docs site (via Docusaurus-style frontmatter and categories).
Changes:
- Expanded
grafana-alertcheck/README.mdwith a clear product summary, quickstart, and links into the docs tree. - Added a new
grafana-alertcheck/docs/documentation set covering overview, evaluation model, advanced scheduling/budget, architecture invariants, and reference material (CLI + log format). - Introduced Docusaurus category metadata (
_category_.yaml) for navigation and generated index pages.
File summaries
| File | Description |
|---|---|
| grafana-alertcheck/README.md | Replaces “under construction” with a Quickstart, behavior summary, and links to the centralized docs. |
| grafana-alertcheck/docs/index.md | New docs landing page with install instructions, quickstarts, exit codes, and pointers to deeper docs. |
| grafana-alertcheck/docs/how-alerts-are-evaluated.md | Explains canonical state model, verdicts, and the coverage proof checks. |
| grafana-alertcheck/docs/advanced.md | Documents scheduling strategy, budget checks, and rationale for not querying history. |
| grafana-alertcheck/docs/architecture.md | Captures invariants and the “pure function seam” / recorder lifecycle for maintainers. |
| grafana-alertcheck/docs/reference/cli.md | CLI usage and flag reference, naming rules, and exit code semantics. |
| grafana-alertcheck/docs/reference/log-format.md | Defines the JSONL log schema and field meanings for debugging artifacts. |
| grafana-alertcheck/docs/category.yaml | Adds top-level docs category metadata and generated-index configuration. |
| grafana-alertcheck/docs/reference/category.yaml | Adds reference-section category metadata and generated-index configuration. |
Review details
Suppressed comments (1)
grafana-alertcheck/docs/index.md:56
- In the single-step Quickstart, "$finished_at" is referenced but never set in the snippet. Using an explicit RFC3339
date(or showing how to capture an emitted value) would make the example self-contained.
grafana-alertcheck check --alerts alerts.txt --to "$finished_at"
- Files reviewed: 9/9 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+22
to
+25
| grafana-alertcheck watch --out /tmp/run.jsonl --alerts alerts.txt | ||
| ./deploy.sh # emits deployed_at=<RFC3339> | ||
| ./verify.sh # emits finished_at=<RFC3339> | ||
| grafana-alertcheck check --in /tmp/run.jsonl --from "$deployed_at" --to "$finished_at" |
Comment on lines
+41
to
+45
| grafana-alertcheck watch --out /tmp/run.jsonl --alerts alerts.txt | ||
| ./deploy.sh # emits deployed_at=<RFC3339> when the rollout is stable | ||
| ./verify.sh # emits finished_at=<RFC3339> when the work is done | ||
| grafana-alertcheck check --in /tmp/run.jsonl --from "$deployed_at" --to "$finished_at" | ||
| ``` |
Tofel
force-pushed
the
dx-5122-alerts-assertion-p15
branch
from
September 7, 2026 09:46
9fa7199 to
a5e3ec7
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stack created with GitHub Stacks CLI • Give Feedback 💬